Initial sbtc docs update #1647
Initial sbtc docs update #1647
Conversation
concepts/sbtc/operations/deposit.md
Outdated
| @@ -1,42 +1,25 @@ | |||
| # sBTC Deposit Operation | |||
|
|
|||
| The deposit operation allows users to convert their BTC to sBTC. This process involves moving BTC from the Bitcoin blockchain to the Stacks blockchain as sBTC. | |||
| The deposit operation enables users to convert their BTC to sBTC, effectively moving value from the Bitcoin blockchain to the Stacks blockchain. This process can be completed within a single Bitcoin block, streamlining the user experience. | |||
There was a problem hiding this comment.
Is it really moving value though? or just adding value?
i think there needs to be some qualifiers about "a single bitcoin block" as well - single block confirmations are inherently dangerous, and bitcoin can and does have forks (meaning a single block confirmation may be reverted).
There was a problem hiding this comment.
@AshtonStephens where are we with single Bitcoin block confirmations in regards to potential forks? I remember briefly having this conversation with you but can't remember why we said single block confirmations for deposits.
|
|
||
| ## User Experience | ||
|
|
||
| From a user's perspective, the deposit process involves: | ||
| From a user's perspective, the deposit process is straightforward. Users initiate a BTC transaction to a specified address and then wait for the transaction to be confirmed on the Bitcoin blockchain. Once confirmed, they receive the equivalent amount of sBTC in their Stacks wallet. |
There was a problem hiding this comment.
i see above that withdrawals are 6 btc blocks - are deposits locked to the same confirmation time?
|
One thing i'm nore sure about is the use of "sortitions" vs using "confirmations". is there a benefit to using one over the other? |
There was a problem hiding this comment.
@kenrogers I think we should remove the concept of "Bootstrap Signers" to only be "sBTC Signers." We did this in the SIP for simplicity and to remove the difference between the two systems for both users and developers.
There was a problem hiding this comment.
This file just refers to the Clarity contract with that name. @AshtonStephens correct me if I'm wrong, but I don't think this refers to the phase 1 bootstrap signers, this is just the contract that is used whenever the signer set changes, so bootstrap here refers to "bootstrapping" the new signer set.
|
|
||
| sBTC empowers developers to build applications on Bitcoin by bridging Bitcoin and [Stacks](https://www.stacks.co/). We achieve this by introducing a fungible token (sBTC) on the Stacks blockchain. The token has the following properties: | ||
| 1. **Bitcoin Compatibility**: Allows Bitcoin holders to participate in the Stacks ecosystem without selling their BTC. | ||
| 2. **DeFi Access**: Enables BTC holders to participate in DeFi. |
There was a problem hiding this comment.
This has been mentioned a few times now that i've noticed, but i don't see how a "BTC holder" may participate in DeFi. If we're not going to say how someone can do that in this doc, i would reword this. I don't have any suggestions at the moment though.
| sBTC empowers developers to build applications on Bitcoin by bridging Bitcoin and [Stacks](https://www.stacks.co/). We achieve this by introducing a fungible token (sBTC) on the Stacks blockchain. The token has the following properties: | ||
| 1. **Bitcoin Compatibility**: Allows Bitcoin holders to participate in the Stacks ecosystem without selling their BTC. | ||
| 2. **DeFi Access**: Enables BTC holders to participate in DeFi. | ||
| 3. **Quick Conversions**: Facilitates rapid movement between BTC and sBTC. |
There was a problem hiding this comment.
Can this be quantified? i.e. ... within 5 bitcoin blocks or whichever is the correct number of blocks
| 1. **Bitcoin Compatibility**: Allows Bitcoin holders to participate in the Stacks ecosystem without selling their BTC. | ||
| 2. **DeFi Access**: Enables BTC holders to participate in DeFi. | ||
| 3. **Quick Conversions**: Facilitates rapid movement between BTC and sBTC. | ||
| 4. **Decentralized Management**: Utilizes a set of signers for maintaining the peg wallet. |
There was a problem hiding this comment.
i would be specific here and mention there will be 15 signers, and possibly link to the SIP defining how those signers shall be chosen (or the working group discussion where the initial signers are listed)
| 2. **DeFi Access**: Enables BTC holders to participate in DeFi. | ||
| 3. **Quick Conversions**: Facilitates rapid movement between BTC and sBTC. | ||
| 4. **Decentralized Management**: Utilizes a set of signers for maintaining the peg wallet. | ||
| 5. **Community Governance**: Involves the community in key decisions, such as selecting the initial signing set. |
There was a problem hiding this comment.
Same as above - i'm not sure how accurate/informative needs to be, but it feels like these statements are missing context and introduce questions that aren't being answered.
the counter argument is that it's not relevant for the doc, and would just add more text to read through vs being shorter and easier to digest.
|
|
||
| Other tokens which try to achieve the same end as sBTC are | ||
| Understanding sBTC requires familiarity with several key concepts. |
There was a problem hiding this comment.
nit: this needs segue into what the concepts are.
either a numbered or bullet list, or simply a colon or something at the end of the sentence.
|
|
||
| While these tokens all achieve the same value as BTC, they maintain BTC reserves through trusted entities. sBTC is the only truly decentralized Bitcoin backed asset on Stacks. | ||
| sBTC is a SIP-010 token on the Stacks Blockchain that can be converted back to BTC on the Bitcoin Blockchain. The key property of sBTC is its 1:1 peg to Bitcoin, meaning 1 sBTC is always equivalent to 1 BTC. |
|
|
||
| Bitcoin holders can do two things to interact with sBTC, deposit and withdraw. Both of these operations are controlled through special Bitcoin transactions. | ||
| The sBTC UTXO is the single unspent transaction output (UTXO) on the Bitcoin blockchain that holds the entire BTC balance pegged into sBTC. This UTXO is managed and maintained by the sBTC Signers. |
There was a problem hiding this comment.
| The sBTC UTXO is the single unspent transaction output (UTXO) on the Bitcoin blockchain that holds the entire BTC balance pegged into sBTC. This UTXO is managed and maintained by the sBTC Signers. | |
| The sBTC UTXO is the single unspent transaction output (UTXO) on the Bitcoin blockchain that holds the entire BTC balance pegged into sBTC. This UTXO is managed and maintained by the set of sBTC Signers. |
|
|
||
| The following diagram illustrates the deposit and withdrawal flows. | ||
| - Signing sBTC operations | ||
| - Communicating with contracts on the Stacks chain |
There was a problem hiding this comment.
This is a little nebulous - will they communicate with any contract, or just the sbtc contracts?
| Next let's take a deeper look at the design of sBTC. | ||
| The sBTC Signer Set is the group of all sBTC signers. This set has full democratic access to the sBTC UTXO. Key properties include: | ||
|
|
||
| - Selected through a community vote weighted by STX holdings |
There was a problem hiding this comment.
I don't know if this is true - the initial set of signers was not chosen through a vote, only the criteria of how they were selected (and no vote has taken place as of yet)
| - Responsible for maintaining the security of the peg wallet | ||
| - Ability to rotate their private keys for enhanced security | ||
|
|
||
| ### Emily API |
There was a problem hiding this comment.
Can we link to teh github repo or other API docs? I'd like to know more about this API
|
|
||
| ### SIP-010 Token | ||
|
|
||
| sBTC adheres to the SIP-010 standard for fungible tokens on the Stacks blockchain. This ensures compatibility with wallets and applications that support the SIP-010 standard. |
There was a problem hiding this comment.
nit: add link to the ratified SIP
|
|
||
| ## Overview | ||
|
|
||
| - sBTC Signers have the ability to rotate their private keys. |
There was a problem hiding this comment.
I think this claim needs more context - can we link to a SIP or repo/docs that define how this occurs?
|
|
||
| - sBTC Signers have the ability to rotate their private keys. | ||
| - This feature enhances the long-term security of the sBTC system. | ||
| - Key rotation is coordinated among signers and requires on-chain voting. |
There was a problem hiding this comment.
this is a bit unclear - does a key rotation need a vote from the full community, or is it a smaller vote (i.e. the signers themselves call a vote with the other signers)
|
|
||
| ## sbtc-token | ||
|
|
||
| This contract implements the sBTC token, following the SIP-010 fungible token standard. |
|
|
||
| ## Conclusion | ||
|
|
||
| These contracts work together to create a decentralized system for managing sBTC, a synthetic representation of Bitcoin on the Stacks blockchain. The contracts handle key operations such as minting sBTC through deposits, burning sBTC through withdrawals, managing the signer set, and maintaining the overall state of the protocol. |
There was a problem hiding this comment.
| These contracts work together to create a decentralized system for managing sBTC, a synthetic representation of Bitcoin on the Stacks blockchain. The contracts handle key operations such as minting sBTC through deposits, burning sBTC through withdrawals, managing the signer set, and maintaining the overall state of the protocol. | |
| Collectively, these contracts work together to create a decentralized system for managing sBTC, a synthetic representation of Bitcoin on the Stacks blockchain. The contracts handle key operations such as minting sBTC through deposits, burning sBTC through withdrawals, managing the signer set, and maintaining the overall state of the protocol. |
|
|
||
| ## Overview | ||
|
|
||
| The sBTC Deposit contract (`sbtc-deposit.clar`) manages the deposit process for the sBTC system. It handles the validation and minting of sBTC tokens when users deposit Bitcoin, and interacts with the sBTC Registry contract to update the protocol state. |
There was a problem hiding this comment.
do we have contracts we can link to? i imagine that there will be a repo with this contracts since they're not deployed yet
There was a problem hiding this comment.
same comment applies to all mentions later of xxx-contract.clar - would be great have them link to the actual contract
| @@ -0,0 +1,73 @@ | |||
| # Emily API | |||
|
|
|||
| Emily is an API that helps facilitate and supervise the sBTC Bridge, serving as a programmatic liaison between sBTC users and signers. | |||
There was a problem hiding this comment.
if there is an openapi.yml, might be helpful to share that later in this document since that's what devs look for
|
|
||
| The Stacks blockchain uses a consensus mechanism called proof of transfer, or PoX, in order to mint new blocks. On each Bitcoin block miners on the Stacks blockchain each sacrifice some amount of Bitcoin in a bid to win the right to make the next few Stacks blocks, where they retain the right to keep making Stacks blocks until the next Bitcoin block occurs and the latest bidding round elects a new Miner. Signers (validators equivalents for the Stacks Blockchain) look at the Bitcoin blocks and approve new Stacks blocks based on which miner currently has the right to make Stacks blocks, and they only approve new blocks from the Signers that won the most recent bid on the Bitcoin block within the fork that they collectively consider to be the “best”. The Stacks blockchain can only have new blocks added if the Signers agree that the miner who proposed it is the winner of the bid on the Bitcoin blockchain, and all the Signers are voting on which block should be added, effectively collectively deciding which Bitcoin fork is the best one. | ||
|
|
||
| Here’s an important part: if the Signers believe that there’s a new and better Bitcoin fork that differs from the one that the last sever Stacks blocks had been mined on, they’ll then only approve new Stacks blocks that build off of Stacks blocks that are tied to that new fork. As in, every Stacks block that was built on Bitcoin Blocks in the other Bitcoin fork that aren’t in this new fork are considered invalid; thus the Stacks blockchain forks too. |
There was a problem hiding this comment.
| Here’s an important part: if the Signers believe that there’s a new and better Bitcoin fork that differs from the one that the last sever Stacks blocks had been mined on, they’ll then only approve new Stacks blocks that build off of Stacks blocks that are tied to that new fork. As in, every Stacks block that was built on Bitcoin Blocks in the other Bitcoin fork that aren’t in this new fork are considered invalid; thus the Stacks blockchain forks too. | |
| Here’s an important part: if the Signers believe that there’s a new and better Bitcoin fork that differs from the one that the last several Stacks blocks had been mined on, they’ll then only approve new Stacks blocks that build off of Stacks blocks that are tied to that new fork. As in, every Stacks block that was built on Bitcoin Blocks in the other Bitcoin fork that aren’t in this new fork are considered invalid; thus the Stacks blockchain forks too. |
|
|
||
| ## User Experience | ||
|
|
||
| From a user's perspective, the deposit process involves: | ||
| From a user's perspective, the deposit process is straightforward. Users initiate a BTC transaction to a specified address and then wait for the transaction to be confirmed on the Bitcoin blockchain. Once confirmed, they receive the equivalent amount of sBTC in their Stacks wallet. |
There was a problem hiding this comment.
i see above that withdrawals are 6 btc blocks - are deposits locked to the same confirmation time?
|
|
||
| The Peg Wallet UTXO is a fundamental element of the sBTC system, serving as the Bitcoin backing for all sBTC tokens in circulation. This system employs a Single UTXO Model, where the sBTC peg wallet is consistently represented as a single Unspent Transaction Output (UTXO) on the Bitcoin blockchain. This design choice offers simplicity and improved efficiency in managing the peg wallet. | ||
|
|
||
| UTXO management falls under the responsibility of the Signer coordinator. This entity consolidates all deposit and withdrawal requests, creating optimized batches that can be processed within a single UTXO. The new UTXO is created by spending the amount from the previous UTXO, adding confirmed deposits, and subtracting confirmed withdrawals. |
There was a problem hiding this comment.
I don't like the use of "This entity" here. can it be rephrased like "The set of sBTC signers will consolidate..."?
|
Overall it looks really good - just a few minor requested changes and some minor nits to resolve |
Update sBTC docs with new design